/***
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 *    Linking this library statically or dynamically with other modules
 *    is making a combined work based on this library. Thus, the terms and
 *    conditions of the GNU General Public License cover the whole
 *    combination.
 *
 *    As a special exception, the copyright holders of this library give
 *    you permission to link this library with independent modules to
 *    produce an executable, regardless of the license terms of these
 *    independent modules, and to copy and distribute the resulting
 *    executable under terms of your choice, provided that you also meet,
 *    for each linked independent module, the terms and conditions of the
 *    license of that module.  An independent module is a module which
 *    is not derived from or based on this library.  If you modify this
 *    library, you may extend this exception to your version of the
 *    library, but you are not obligated to do so.  If you do not wish
 *    to do so, delete this exception statement from your version.
 *
 *    Project: www.simpledbm.org
 *    Author : Dibyendu Majumdar
 *    Email  : d dot majumdar at gmail dot com ignore
 */
package org.simpledbm.network.client.api;

import org.simpledbm.common.api.tx.IsolationMode;
import org.simpledbm.typesystem.api.TableDefinition;

/**
 * A Session encapsulates an interactive session with the server. Each session
 * can only have one active transaction at any point in time. Clients can open
 * multiple simultaneous sessions.
 * <p>
 * All sessions created by a SessionManager share a single network connection
 * to the server.
 */
public interface Session {

    /**
     * Closes the session. If there is any outstanding transaction, it will be
     * aborted. Sessions should be closed by client applications when no longer
     * required, as this will free up resources on the server.
     */
    public void close();

    /**
     * Starts a new transaction. In the context of a session, only one
     * transaction can be active at a point in time, hence if this method will
     * fail if there is already an active transaction.
     * 
     * @param isolationMode Lock isolation mode for the transaction
     */
    public void startTransaction(IsolationMode isolationMode);

    /**
     * Commits the current transaction; an exception will be thrown if there is
     * no active transaction.
     */
    public void commit();

    /**
     * Aborts the current transaction; an exception will be thrown if there is
     * no active transaction
     */
    public void rollback();

    /**
     * Creates a table as specified. The table will be created using its own
     * transaction independent of the transaction managed by the session.
     * 
     * @param tableDefinition The TableDefinition
     */
    public void createTable(TableDefinition tableDefinition);

    /**
     * Obtains a reference to the table. The Table container will be locked in
     * SHARED mode.
     * 
     * @param containerId The ID of the table's container
     * @return A Table object
     */
    public Table getTable(int containerId);

    /**
     * Gets the SessionManager that is managing this session.
     */
    public SessionManager getSessionManager();

    /**
     * Gets the unique id associated with this session.
     */
    public int getSessionId();

}
